feat(spec): parse usage comments from strings by jdx · Pull Request #782 · jdx/usage

jdx · 2026-08-07T19:09:24Z

Summary

add Spec::parse_script_str for parsing embedded USAGE comments from an in-memory script
preserve file-backed parsing diagnostics and filename inference
correct the documented supported USAGE comment markers
add coverage for parsing a complete script string

This gives embedders a direct Rust API without requiring a temporary file or deserializing Spec.

Closes #781.

Validation

cargo test -p usage-lib --all-features
cargo clippy -p usage-lib --all-features -- -D warnings

Note

Low Risk
Additive public API and clearer errors in spec parsing only; no auth, I/O, or runtime behavior changes beyond new entry points.

Overview
Adds Spec::parse_script_str so embedders can turn a script body into a Spec without writing a temp file or hand-parsing KDL. File-based parse_script now shares parse_script_with_path with the string API; only the file path still drives default bin/name inference.

String parsing uses an empty source path, so relative include paths fail with "relative includes require a source file" instead of a parent-directory error. Docs now describe the real markers (#USAGE, //USAGE, ::USAGE, and [USAGE] variants) rather than # USAGE:.

Tests cover a full embedded script and the relative-include rejection.

^{Reviewed by Cursor Bugbot for commit 4cc4e74. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

New Features
- Added support for extracting usage specifications from #USAGE, //USAGE, ::USAGE, and [USAGE] markers.
- Added a public API for parsing embedded usage specifications directly from strings.
- String-based parsing now supports absolute includes without requiring filename-based defaults.
Bug Fixes
- Improved script parsing consistency across supported usage-marker formats.
- Added validation to reject unsupported relative includes when parsing strings.

coderabbitai · 2026-08-07T19:09:42Z

📝 Walkthrough

Walkthrough

Changes

Script usage parsing

Layer / File(s)	Summary
Usage marker extraction and parser delegation `lib/src/spec/mod.rs`	Documentation lists `#USAGE`, `//USAGE`, `::USAGE`, and `[USAGE]` markers. `parse_script` delegates parsing to a shared path-aware helper.
String parsing API and validation `lib/src/spec/mod.rs`	`Spec::parse_script_str` parses usage specifications from strings without filename-derived defaults. Relative includes return a source-path error. Tests cover parsed values and this error.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ScriptString
  participant parse_script_str
  participant SharedParser
  participant Spec
  ScriptString->>parse_script_str: raw script input
  parse_script_str->>SharedParser: extract usage markers
  SharedParser->>Spec: parse usage specification
  Spec-->>parse_script_str: Spec or UsageErr

Poem

I’m a rabbit with scripts in my nest,
#USAGE markers now parse at their best.
From strings they emerge,
With flags in a surge,
And clean Spec results pass every test.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds the requested public API for parsing USAGE comments from in-memory script strings [`#781`].
Out of Scope Changes check	✅ Passed	The marker fixes, include validation, diagnostics, filename behavior, and tests directly support string-based script parsing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding string-based parsing for usage comments.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-08-07T19:11:02Z

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	`▂▂▁▂▇▇▇█▇▇`	110,500,751 → 110,483,839	-0.02%	10.47 → 10.75ms	+2.71%
startup	`▁▃█▄▄▅▃██▃`	1,197,833 → 1,195,781	-0.17%	0.92 → 0.98ms	+6.11%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{4cc4e7421706 vs 37e8bd3608a5 · measured on the runner, not pushed to the history.}

greptile-apps · 2026-08-07T19:11:17Z

Greptile Summary

Adds an in-memory script parsing API while preserving file-backed parsing behavior and diagnostics.

Introduces Spec::parse_script_str and a shared parsing helper.
Rejects relative includes when no source path is available while retaining absolute includes.
Corrects documentation for supported USAGE markers and adds regression coverage.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported relative-include issue is fixed, and no blocking failure remains.

Important Files Changed

Filename	Overview
lib/src/spec/mod.rs	Adds string-backed script parsing and correctly closes the previously reported ambient-working-directory include behavior by rejecting relative includes without a source path.

_{Reviews (2): Last reviewed commit: "fix(spec): reject relative string includ..." | Re-trigger Greptile}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/src/spec/mod.rs`:
- Around line 129-144: Fix parse_script_str and parse_script_with_path so
relative include directives resolve from the intended base path rather than the
repository root. Prefer extending the string-spec API to accept an explicit base
path and pass it into ParsingContext; otherwise keep parse_script_str pathless
and explicitly reject or document relative includes for it, while preserving
path-based resolution in parse_script_with_path.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f5430be9-5f91-4dda-948d-32147454ef5e

📥 Commits

Reviewing files that changed from the base of the PR and between f3f9761 and f47fe0d.

📒 Files selected for processing (1)

lib/src/spec/mod.rs

feat(spec): parse usage comments from strings

f47fe0d

jdx mentioned this pull request Aug 7, 2026

Expose parsing #USAGE comments from a script in a string in Rust API #781

Closed

greptile-apps Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread lib/src/spec/mod.rs

coderabbitai Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread lib/src/spec/mod.rs

fix(spec): reject relative string includes

4cc4e74

jdx merged commit f47cf92 into main Aug 7, 2026
9 checks passed

jdx deleted the agent/parse-script-str branch August 7, 2026 19:21

jdx mentioned this pull request Aug 9, 2026

chore: release v5.1.0 #787

Closed

mise-en-dev mentioned this pull request Aug 9, 2026

chore: release v5.1.0 #789

Merged

BrewTestBot mentioned this pull request Aug 9, 2026

usage 5.1.0 Homebrew/homebrew-core#297930

Merged

Navigation Menu

Uh oh!

feat(spec): parse usage comments from strings - #782

feat(spec): parse usage comments from strings#782
jdx merged 2 commits into
mainfrom
agent/parse-script-str

jdx commented Aug 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 7, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Aug 7, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Aug 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

jdx commented Aug 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Instruction counts

Uh oh!

greptile-apps Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jdx commented Aug 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 7, 2026 •

edited

Loading

github-actions Bot commented Aug 7, 2026 •

edited

Loading

greptile-apps Bot commented Aug 7, 2026 •

edited

Loading